

unit UProgress;

{This unit defines the interface to show the progress of a work to do: ~[link
 IProgressInterface] and ~[link IProgressInterface here].

 Besides that it contains a lot of test-data:~[br]
 Types and other pascal constructs as well as comments.

 This is ~[insertVariable FileType] ~[insertVariable FileName] or also
 ~[link UProgress] or ~[link ~[insertVariable FileName]] and
 ~[linkUnit UProgress] or ~[linkUnit ~[insertVariable FileName]].
 Currently using the generator ~[em ~[insertText DocClass]] (Horror!).

 So that's >= nice & good ;-) and also \_/\_/ some ASCII-Art for testing the
 parsing of comments besides the ~~link command.

 And to test some special characters: ???? &auml;

 ~see IProgressInterface
 ~seeText Delphi-Help
 ~seeText another Test for ~~seeText
}

interface

uses Windows, SysUtils;

//There are some valid (but weird) pascal constructs in this file to test the
//Delphi compiler and the language. Enable/disable compiling by the following
//compiler symbol.


//{$DEFINE DOSOMEPASCALCHECKS} {
{$UNDEF DOSOMEPASCALCHECKS}


type

 { *** * * ***  IProgressInterface  *** * * *** }



  {This Exception can be raised by IProgressInterface, when the action should
   be aborted.}
  EAbortProgress = class(EAbort);


  {This type defines the interface for classes, which can be used to display
   the progress of an action. The action should be aborted, when the interface
   returns false with one of their progress functions or raises the
   ~[link EAbortProgress] exception. }
  IProgressInterface = interface

//    function GetInterface(const IID: TGUID; out Obj): Boolean;

    {Prepares the object for a completely new action to show the progress of. }
    procedure Prepare;

    {Sets the text of the currently executed action.
    ~param Text the currently executed action }
    procedure SetWorkText(const Text: String);
    {Sets the text showing the progress of the action, like "Item 5 of 10".
    ~param Text text of progress of the action
    ~result if the action should be aborted }
    function SetProgressText(const Text: String): Boolean;
    {Sets the text of the currently processed item.
    ~param Text the currently processed item
    ~result if the action should be aborted }
    function SetProcessText(const Text: String): Boolean;

    {Sets the number of units to process.
    ~param NewMax the number of units to process }
    procedure SetMaximum(NewMax: Integer);


    {Resets the display of progress, so that another action can be started and
     be progressed. }
    procedure Reset;

    {Sets if an exception should be raised when the progress is being stepped
     but the action should be aborted.
    ~param RaiseOnAbort if an exception should be raised but the action should
                        be aborted }
    procedure SetThrowExceptionOnStepIfAbort(RaiseOnAbort: Boolean);


    {Steps the progress.
    ~result if the action should be aborted
    ~exception EAbortProgress if set with ~[link
                              SetThrowExceptionOnStepIfAbort] and the action
                              should be aborted }
    function StepProgress: Boolean;

    {Returns if the progressing action should be aborted.
    ~result if the action should be aborted }
    function ShouldAbort: Boolean;


    {Called when the action has been finished. May be called more than once. }
    procedure Finished;
  end;






 { *** * * ***  TProgressAdapter  *** * * *** }

  {A class that does nothing to show the progress. Can be used to create
   other IProgressInterface implementing classes more easily. }
  TProgressAdapter = class(TInterfacedObject, IProgressInterface)
  private
  public
    //Prepares the object for a completely new action to show the progress of.
    procedure Prepare; virtual;

    //Sets the text of the currently executed action.
    procedure SetWorkText(const Text: String); virtual;
    //Sets the text showing the progress of the action, like "Item 5 of 10".
    function SetProgressText(const Text: String): Boolean; virtual;
    //Sets the text of the currently processed item.
    function SetProcessText(const Text: String): Boolean; virtual;


    //Sets the number of units to process.
    procedure SetMaximum(NewMax: Integer); virtual;


    //Resets the display of progress, so that another action can be started and
    //be progressed. }
    procedure Reset; virtual;

    //Sets if an exception should be raised when the progress is being stepped
    //but the action should be aborted.
    procedure SetThrowExceptionOnStepIfAbort(RaiseOnAbort: Boolean); virtual;


    //Steps the progress.
    function StepProgress: Boolean; virtual;

    //Returns if the progressing action should be aborted.
    function ShouldAbort: Boolean; virtual;

    //Called when the action has been finished. May be called more than once.
    procedure Finished; virtual;


  end;


implementation





 { *** * * ***  TProgressAdapter  *** * * *** }



{Prepares the object for a completely new action to show the progress of. }
procedure TProgressAdapter.Prepare;
begin
end;


{Sets the text of the currently executed action.
~param Text the currently executed action }
procedure TProgressAdapter.SetWorkText(const Text: String);
begin
end;

{Sets the text showing the progress of the action, like "Item 5 of 10".
~param Text text of progress of the action
~result if the action should be aborted }
function TProgressAdapter.SetProgressText(const Text: String): Boolean;
begin
 Result := False;
end;

{Sets the text of the currently processed item.
~param Text the currently processed item
~result if the action should be aborted }
function TProgressAdapter.SetProcessText(const Text: String): Boolean;
begin
 Result := False;
end;


{Sets the number of units to process.
~param NewMax the number of units to process }
procedure TProgressAdapter.SetMaximum(NewMax: Integer);
begin
end;


{Resets the display of progress, so that another action can be started and
 be progressed. }
procedure TProgressAdapter.Reset;
begin
end;

{Sets if an exception should be raised when the progress is being stepped
 but the action should be aborted.
~param RaiseOnAbort if an exception should be raised but the action should
                    be aborted }
procedure TProgressAdapter.SetThrowExceptionOnStepIfAbort(RaiseOnAbort:
                                                                      Boolean);
begin
end;

{Steps the progress.
~result if the action should be aborted
~exception EAbortProgress if set with ~[link SetThrowExceptionOnStepIfAbort]
                          and the action should be aborted }
function TProgressAdapter.StepProgress: Boolean;
begin
 Result := False;
end;

{Returns if the progressing action should be aborted.
~result if the action should be aborted }
function TProgressAdapter.ShouldAbort: Boolean;
begin
 Result := False;
end;

{Called when the action has been finished. May be called more than once. }
procedure TProgressAdapter.Finished;
begin
end;



end.





